9  API Auth Implementation

Here is a safe dual-auth rollout you can execute in this repository.

Implementation Plan

  1. Add AD token validation in OWIN while keeping NTLM active.
  2. Update identity extraction to prefer bearer-token claims and fallback to existing Windows identity.
  3. Add feature flags so you can switch behavior without redeploying code.
  4. Update SignalR auth path to use the same identity resolver.
  5. Pilot and cut over, then disable NTLM.

Files To Change First

  1. Startup.cs
    Add bearer-token middleware before WebApi middleware.
  2. AppAuthorizationMessageHandler.cs
    Replace hard dependency on HttpContext Windows identity with a resolver that checks token claims first.
  3. SignalrAuthorizationAttribute.cs
    Use the same resolver to read identity from SignalR token/cookies.
  4. Web.config:630 Add new auth flags and Entra settings; later switch auth mode after cutover.

Config You Should Add
In appSettings:

  1. Api.Settings.Auth.Mode = Dual | TokenOnly | WindowsOnly
  2. Api.Settings.Auth.Entra.TenantId
  3. Api.Settings.Auth.Entra.Audience
  4. Api.Settings.Auth.Entra.ValidIssuers
  5. Api.Settings.Auth.Claims.UsernamePriority = preferred_username;upn;email
  6. Api.Settings.Auth.EnableWindowsFallback = true initially

Identity Resolution Logic
Create one resolver service and use it from both API handler and SignalR:

  1. If bearer token exists and is valid:
    • Read username claim by priority: preferred_username, then upn, then email.
    • Optionally map UPN to DOMAINif your PrincipalUserQuery expects that.
  2. Else if Windows principal exists:
    • Use existing HttpContext.Current.User.Identity.Name behavior.
  3. Else:
    • Return 401/403 as now.

Then keep current PrincipalUserQuery path unchanged so authorization/business rules remain stable.

Middleware Order (important)
In Startup:

  1. Use token auth middleware first.
  2. Then UseWebApi.
  3. Keep your existing delegating handlers.
    This ensures claims principal is available before AppAuthorizationMessageHandler runs.

SignalR Path
For SignalR:

  1. Accept access token in query/header (depending on client transport support).
  2. Resolve identity using same claim priority.
  3. Keep impersonation query parameter behavior unchanged.

Rollout Strategy

  1. Stage 1 (Dual mode):
  1. Stage 2 (Pilot users/departments):
    • Force selected front-end clients to send bearer tokens.
    • Monitor 401/403 and user-mapping misses.
  2. Stage 3 (Token-only):
    • Switch Api.Settings.Auth.Mode to TokenOnly.
    • Enable anonymous at IIS and disable Windows auth at host level.
  3. Stage 4 (Cleanup):
    • Remove NTLM-only branches after 2-4 weeks stable.

Validation Checklist

  1. Existing desktop domain user opens app and gets in with no login prompt.
  2. Token user maps to same PrincipalUser as old NTLM path.
  3. Impersonation header still works.
  4. Webhooks/system URLs continue to use system account path.
  5. SignalR hub authorization still succeeds.
  6. External app and certificate-protected endpoints still pass.

Risk Controls

  1. Keep EnableWindowsFallback true until mapping is proven.
  2. Add audit logs for username source and mapped principal id.
  3. Add feature flag kill switch to revert to WindowsOnly quickly.